File

Many of these primitives output an error number, referred to in the descriptions below by the Name ErrorNum and the Type <file error>. An ErrorNum of 0 indicates success, while any other integer indicates that the primitive has not performed its task. Error numbers, provided by the Macintosh File Manager, are further explained in Inside Macintosh.

Some of these primitives can also have an integer input or output called FileNum, which consists of a Macintosh file reference number in its lower 16 bits, and a volume reference number in its upper 16 bits.

Macintosh Resource Types (including File Types) are Pascal “packed array of char” data types, which appear as integers, but can be input as characters within single quotes, as in 'TEXT'.

_________________________________________________
 
                   close
 *269*

Input types: integer

Output types: <file error>

Description: 
Closes the file referenced by FileNum. 

See also:  create, delete, open, rename

_________________________________________________
                         create
 *269*

Input names: Name;  [VolID;  [CreateType;  [FileType]]]

Input types: string;  [integer;  [integer;  [integer]]]

Defaults: 
VolID = 0, CreateType = 0, FileType = 'TEXT'.

Output names: ErrorNum

Output types: <file error>

Description: 
Creates a new file called Name.

See also:  close, delete, open, rename

_________________________________________________
                            delete
 *270*

Input names: Name;  [VolID]

Input types: string;  [integer]

Defaults: 
VolID = 0.

Output names: ErrorNum

Output types: <file error>

Description: 
Deletes the file called Name. 

See also: 
close, create, open, rename

_________________________________________________
                                             file-size
 *270*

Input types: integer

Output types: <file error> ; integer | null

Description: 
If ErrorNum = 0, Size is the size in bytes of the file referenced by FileNum. Otherwise Size is NULL. 

See also:  get-position, set-position

_________________________________________________
                                                get-file
 *270*

Input types: list of integer

Output types: string | null;  integer | null;  integer | null

Description: 
An Open File dialog is opened displaying either files of all types, if TypeList is the empty list, or otherwise files of the types specified by TypeList. If the Open button of the dialog is clicked, Name, VolID, and FileType are the name, volume number, and type of the selected file; otherwise they are NULL.

Example:
Opening a text file:  if none of get-file’s outputs are NULL, a file was selected, and its name and VolID are passed to open.  If open’s ErrorNum output is 0, the file has been successfully opened, and its FileNum is passed on for further processing.

 
See also:  put-file

_________________________________________________
                                             get-position
*271*

Input types: integer

Output types: <file error>;  integer | null

Description: 
If ErrorNum is 0, Offset is the current position of the file pointer (the next byte to be read or written) in the file referenced by FileNum. Otherwise Offset is NULL.

See also:  set-position, file-size

_________________________________________________
                                     load
 *271*

Input names: FileName; [VolumeID]

Input types: string; [integer]

Defaults: VolumeID = 0

Output names: ErrorNum; Data

Output types: <file error>; <any>

Description: 
Returns the Data contained in the file called FileName. Optional input is the ID of the volume (working directory) from which to read the file (0 = current folder). ErrorNum 0 is no error, < 0 is Mac file system error, 1 is no name information error, 2 is version error, and 3 is class mapping error. See chapter 9, “The Prograph Compiler” for a full discussion.

_________________________________________________
                                                 open
 *272*

Input names: Name;  [VolID;  [Permission]]

Input types: string;  [integer;  [integer]]

Defaults: VolID = 0, Permission = 3

Output names: ErrorNum;  FileNum

Output types: <file error>;  integer | null

Description: 
The file called Name is opened, with access level specified by Permission (1 = read, 2 = write, 3 = read/write). If ErrorNum is 0, FileNum is the reference to the opened file. 

See also:  close, create, delete, rename

_________________________________________________

                                          prograph-file
*272*

Output types: string;  integer; integer

Description: 
FileName and VolID are the name and volume number of the current Prograph file.  WDirID is the directory number of the current Prograph file.

Compiler: Not supported.

_________________________________________________
                                            put-file
 *272*

Input types: string;  string

Output types: string | null;  integer | null

Description: 
A Save File dialog is opened displaying the given Prompt and an editable field containing NameIn. If the Save button is clicked, NameOut and VolID are respectively the string in the editable field and the number of the selected volume. If the Cancel button is clicked, NameOut and VolID are both NULL. 

See also:  get-file

_________________________________________________
 
                                  read
 *273*

Input types: integer;  integer

Output types: integer;  ABlock | null

Description: 
Starting at the position indicated by the current file pointer, Size bytes are read from the file referenced by FileNum into Block. 

See also:  read-line, write, write-line

_________________________________________________
                                             read-line
 *273*

Input names: FileNum;  Size;  [LineEnd]

Input types: integer;  integer;  [integer]

Defaults: LineEnd = 13 (return)

Output names: ErrorNum;  Line

Output types: <file error>;  string | null

Description: 
If ErrorNum = 0, Line is a string of characters read from the file referenced by FileNum starting at the position indicated by the current file pointer, until either Size bytes have been read or a byte of value LineEnd is encountered.  If LineEnd = -1, Size bytes are read. If ErrorNum ≠ 0, Line is NULL.  

See also:  read, write, write-line

_________________________________________________
                                       rename
 *274*

Input names: OldName;  NewName;  [VolID]

Input types: string;  string;  [integer]

Defaults: 
VolID = 0 

Output names: ErrorNum

Output types: <file error>

Description: 
The file called OldName is renamed NewName.

See also:  close, create, delete, open

_________________________________________________
                                save
 *274*

Input names: Data; FileName; [VolumeID; [CreatorType; [FileType]]]

Input types: <any>; string; [integer; [integer; [integer]]]

Defaults: VolumeID = 0; CreatorType = 0; FileType = 0

Output names: ErrorNum

Output types: <file error>

Description: 
Writes the Data to the file called FileName. If a file of that name already exists, it is first erased (the resource fork is untouched).  Optional inputs include the ID of the volume on which to write the file (0 = current folder) and the Creator and File type designators to assign to the file, for example, 'PROG', 'TEXT'.  ErrorNum 0 is no error, < 0 is Mac file system error, and 0 is no name information error. See chapter 9, “The Prograph Compiler” for a complete description.

_________________________________________________
                                      set-position
*275*

Input types: integer;  integer

Output types: <file error>

Description: 
Sets the file pointer of the file referenced by FileNum  to Offset bytes from the start of the file. If Offset is -1, sets the file pointer to the end of the file.
See also:  get-position, file-size

_________________________________________________
                                               write
 *275*

Input types: integer;  ABlock;  integer

Output types: <file error>

Description: 
Writes Size bytes  from Block to the file referenced by FileNum, starting at the position indicated by the current file pointer.

See also:  read, read-line, write-line

_________________________________________________
                                          write-line
 *275*

Input names: FileNum;  Data;  [LineEnd]

Input types: integer;  <any>;  [integer]

Defaults: LineEnd = 13 (return)

Output names: ErrorNum

Output types: <file error>

Description: 
Starting at the position indicated by the current file pointer, writes a textual representation of Data to the file referenced by FileNum, followed by the character specified by LineEnd. If LineEnd = -1, no end-of-line character is written.